docs: formal Bayesian specification of autofit.graphical (EP review phase 2)#1334
Merged
Conversation
…ical docstrings) - autofit/graphical/README.md (new): the mathematics as implemented — factor-graph model, exponential-family mean field, the EP step (cavity / tilted / moment-matching projection / damped division as natural-parameter EMA), the three factor-optimiser paths, convergence criterion + KL direction contract, evidence decomposition, deterministic-variable mechanisms, parallel-EP semantics; each equation anchored to its implementing class/method. - MeanField.update_factor_mean_field: damped-update equations, delta semantics, invalid-projection fallback. - MeanField.kl: KL direction contract (m.kl(other) == KL(m||other)). - FactorApproximation: fix damped-update docstring error ((q_a^f)^(1-d) -> (q_a)^(1-d)). - composed_transform.py: module docstring stating the transform composition-order convention (innermost-first storage; reversal asymmetry) with a worked UniformPrior trace; direction notes on _transform/_inverse_transform; validity condition on TransformedMessage.kl. - AbstractMessage.project: moment-matching projection equations. EP framework review phase 2 (#1333); audit findings context in #1332. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 8, 2026
…ests - autofit/graphical/README.md: new §8 'The lowering contract (declarative → graph)' — every declarative concept and what it lowers to, with invariants (compound priors add no variables; factor_out not reachable by design; PriorFactor exact-hooks gap noted → #1337/#1338). - AGENTS.md: the EP seam rule — inner-layer capability lands in the same PR as its declarative expression or an explicit 'not exposed' entry, plus a seam test. - test_autofit/graphical/test_declarative_deterministic.py: replaced the commented-out PR #1153 illustration with 4 working seam tests pinning the explicit compound-prior lowering (no new variables, graph shape, in-factor realisation, shared-variable connectivity). The model.<property> sugar remains deliberately reverted (be64117). EP review seam recommendations (#1330 wrap-up discussion); Phase 5 recommendation A item 2 delivered independently of the #1336 decision. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Collaborator
Author
|
Scope addition (commit 39eaf55) — the seam-contract work from the two-layer architecture discussion on the review:
The PR is no longer strictly docs-only (one test file), but still zero runtime-behaviour change. Full suite on the branch: 1425 passed / 14 skipped (1422 baseline + 4 seam tests − 1 replaced no-op). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 of the EP framework review (#1333; statistics audit #1332): package-level documentation stating the exact Bayesian machinery
autofit/graphicalimplements, in formal equations, each anchored to the implementing class/method so code can be verified against the stated math line-by-line. Addsautofit/graphical/README.md(the specification) plus targeted docstring upgrades at the load-bearing statistical points (update_factor_mean_field,MeanField.kl,TransformedMessagecomposition convention,AbstractMessage.project), and fixes one incorrect docstring equation (#1332 F5).API Changes
None — documentation only. No signatures, symbols or behaviour changed.
See full details below.
Test Plan
pytest test_autofit/full suite in the task worktree (counts in validation checklist)pytest test_autofit/graphical/ test_autofit/messages/— 200 passed (pre-ship)Full API Changes (for automation & release notes)
Removed
Added
autofit/graphical/README.md; docstrings on existing methods).Migration
Validation checklist (--auto run)
🤖 Generated with Claude Code